Skip to content

refactor: remove orphaned directories and overclaiming stub files#3244

Merged
MohammadHaroonAbuomar merged 7 commits into
mainfrom
liamcrumm/hypervisor-remove-stub-features
Jul 2, 2026
Merged

refactor: remove orphaned directories and overclaiming stub files#3244
MohammadHaroonAbuomar merged 7 commits into
mainfrom
liamcrumm/hypervisor-remove-stub-features

Conversation

@liamcrumm

@liamcrumm liamcrumm commented Jul 1, 2026

Copy link
Copy Markdown
Contributor

Description

This PR is intended to clean up the directory structure and overclaimed dead capabilities. Several capabilities in agent hypervisor were stubbed but claimed as working, and several of the directories were as empty redirects for backward compatibility during a past migration. This is intended to bring the repo closer to a logical state where code sits in intuitive spots and claimed capabilities are fully implemented.

I also removed the agent-governance-gate.ym, governance-attestation and security-scan ci flows since they were dead code and not being run on PR.

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Maintenance (dependency updates, CI/CD, refactoring)
  • Security fix

Package(s) Affected

  • agent-os-kernel
  • agent-mesh
  • agent-runtime
  • agent-sre
  • agent-governance
  • docs / root

Checklist

  • My code follows the project style guidelines (ruff check)
  • I have added tests that prove my fix/feature works
  • All new and existing tests pass (pytest)
  • I have updated documentation as needed
  • I have signed the Microsoft CLA

Attribution & Prior Art

  • This contribution does not contain code copied or derived from other projects without attribution
  • Any external projects that inspired this design are credited in code comments or documentation
  • If this PR implements functionality similar to an existing open-source project, I have listed it below

Prior art / related projects (if any):

AI Assistance

  • I can explain every meaningful change in this PR: what it does, why, and what tradeoffs were considered
  • I have run tests and verification appropriate for this change
  • No part of this PR was autonomously submitted by an AI agent without my review
  • I have not used AI to generate review comments on others' PRs

If AI tools materially shaped this change, briefly note what was used:

Worked with Github Copilot on some refactoring parts

IP, Patents, and Licensing

  • This contribution does not implement patent-pending or patent-encumbered techniques
  • This contribution does not require an NDA or licensing agreement to understand or use
  • Any AI tools used have terms compatible with the MIT License

Related Issues

@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

PR Review Summary

Check Status Details
🔍 Code Review ⚠️ Missing No current-run comment
🛡️ Security Scan ⚠️ Missing No current-run comment
🔄 Breaking Changes ⚠️ Missing No current-run comment
📝 Docs Sync ⚠️ Missing No current-run comment
🧪 Test Coverage ⚠️ Missing No current-run comment

Verdict: ⚠️ AI review incomplete; ready for human review

AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims.

@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

  • .github/workflows/agent-governance-gate.yml

@github-actions github-actions Bot added documentation Improvements or additions to documentation dependencies Pull requests that update a dependency file tests agent-hypervisor agent-hypervisor package size/XL Extra large PR (500+ lines) and removed documentation Improvements or additions to documentation dependencies Pull requests that update a dependency file tests agent-hypervisor agent-hypervisor package labels Jul 1, 2026
@github-actions

github-actions Bot commented Jul 1, 2026

Copy link
Copy Markdown

📦 Dependency diff (SBOM)

Comparing mainliamcrumm/hypervisor-remove-stub-features.

✅ No dependency changes detected.

@github-actions github-actions Bot added documentation Improvements or additions to documentation dependencies Pull requests that update a dependency file tests agent-hypervisor agent-hypervisor package scripts/ci/cd labels Jul 1, 2026
@liamcrumm liamcrumm changed the title Refactor to remove orphaned directories and overclaiming stub files refactor: remove orphaned directories and overclaiming stub files Jul 1, 2026
liamcrumm and others added 4 commits July 1, 2026 23:20
Signed-off-by: Liam Crumm <liamcrumm@gmail.com>
Wires the previously-inert action/governance-attestation composite action into a pull_request workflow so the repo runs its own attestation gate instead of only publishing it for downstream consumers. Pins the published toolkit to 4.1.0 and passes the PR body as an input (read via env inside the action, never shell-interpolated). Least-privilege contents:read, SHA-pinned checkout.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Liam Crumm <liamcrumm@gmail.com>
Removes governance tooling that is unused in-repo and non-functional for external consumers: the governance-attestation composite action (encoded Microsoft-internal CELA/RAI/launch-gate checks, unusable as a generic action), the security-scan composite action (redundant with native scanners, referenced by no workflow), and the agent-governance-gate reusable workflow plus scripts/governance_gate.py and examples/github-actions-governance (the workflow calls a script the caller repo does not have, so it cannot run externally). Also removes agent_compliance/governance (validate_attestation), the orphaned validator that only backed the removed attestation action, and the PR workflow that dogfooded it.

Keeps action/action.yml (Agent Governance Verify, wraps the real agt verify) and agent_compliance/security/scanner.py (used by promotion/supply_chain). Updates the A2 regression test and de-references the removed artifacts in docs. Validated: tests/ci 73 pass; docs link checker introduces 0 new broken links.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Liam Crumm <liamcrumm@gmail.com>
core.py verify_behavior: restore the _get_session/get_participant guard that was dropped together with slashing.slash(), so a drift signal on an unknown session or a non-participant agent raises (as before) instead of silently reporting to the external Nexus trust backend. Removes vestigial dead surfaces left by the stub removal: the enable_blockchain_commitment SessionConfig field and the liability/checkpoint/fan-out/gc EventType members (no emitters). Fixes stale docs: terminate_session docstring, AUDIT-COMPLIANCE section 14 (drop the Level-3 MUST for the not-implemented Commitment Engine and the intro mention), exec-control intro (drop quarantine and the blockchain_commitment field row), and the agent-os conformance test comment.

Validated: the verify_behavior repro no longer reproduces (non-participant raises, participant still reported); hypervisor+runtime 753 pass, agent-os conformance 152 pass; ruff clean; 0 new broken doc links.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Liam Crumm <liamcrumm@gmail.com>
@liamcrumm liamcrumm force-pushed the liamcrumm/hypervisor-remove-stub-features branch from 4633a7c to 23295d6 Compare July 1, 2026 23:20
The stub-removal cleanup over-deleted still-valid reference content. This
restores it while keeping the genuine feature removals and the de-claiming
intact.

Docs restored (verified against the live code, no removed symbols reintroduced):
- api-reference.md back to the real 18-route surface with the Table of
  Contents, response-body examples, query/request tables and 404s, plus the
  requires_consensus, requires_sre_witness and actions fields that still exist
- README.md and packages/agent-hypervisor.md back to full configuration,
  architecture and feature docs, with the benchmarks link and standard badges
  restored (PyPI version badge stays out since the standalone package is a
  deprecation stub)
- 11-saga-orchestration and 06-execution-sandboxing back to teaching
  SagaOrchestrator and execution rings; broken classify_action_id samples
  rewritten to the real classify(ActionDescriptor) API and verified runnable
- 13-observability event counts corrected to 30 total (Saga 7, Audit 2)

CI gate fixes:
- add the MIT header to scripts/verify_tutorials_01_34.py
- fix the CODEOWNERS relative link in docs/reference/contributing.md
- add pandas/plotly and ASCII-diagram terms to the cspell dictionary
- normalize licence to license in tutorial 45
- drop the unused CausalViolationError import flagged by code-quality

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Liam Crumm <liamcrumm@gmail.com>
@liamcrumm liamcrumm force-pushed the liamcrumm/hypervisor-remove-stub-features branch from 23295d6 to 9f471a3 Compare July 1, 2026 23:25
@liamcrumm liamcrumm marked this pull request as ready for review July 1, 2026 23:36

@MohammadHaroonAbuomar MohammadHaroonAbuomar left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deletions verified safe: every removed module, script, tutorial, example, and package stub has zero remaining imports, __all__ entries, nav links, or workspace references on this branch. agt-{core,cli,integrations,protocols} are not on PyPI (all 404). scripts/check_dependency_confusion.py change is comment-only. CI is green.

Four items to close before this is approvable.

  1. docs/specs/AUDIT-COMPLIANCE-1.0.md:131 (introduced by this PR): the ASCII diagram now lists DeltaEngine on both L130 and L131. L131 should be the blank-cell padding row that was there before.

  2. .cspell.json:21: drop "tion" (and "reputa", "Orchestr") from the global word list. These were added to silence truncated words inside ASCII boxes at docs/tutorials/45-shift-left-governance.md:51 and agent-governance-python/agent-os/README.md:440. Adding "tion" to the repo-wide dictionary will mask real typos everywhere. Use <!-- cspell:disable-line --> (or a file-scoped cspell:disable block) at the two sites instead.

  3. agent-governance-python/agent-hypervisor/src/hypervisor/session/isolation.py:34-36: IsolationLevel.requires_intent_locks is now dead. Its only consumer was session/intent_locks.py, which this PR deletes; the remaining references are three value-assertion tests at tests/unit/test_session_security.py:73,80,87. Delete the property and those three assertions in this PR.

  4. BREAKING_CHANGES.md: the only edit is subtractive (drops two actions from an existing entry's affected list). Add a new entry logging the removed public symbols from hypervisor and their agent_runtime re-exports: VouchingEngine, SlashingEngine, LiabilityLedger, LiabilityMatrix, QuarantineManager, QuarantineReason, CausalAttributor, IntentLockManager, LockIntent, FanOutOrchestrator, FanOutPolicy, SagaDSLParser, SagaDefinition, CheckpointManager, SemanticCheckpoint, CommitmentEngine, EphemeralGC, VectorClockManager. Public Preview status permits the removal; it should still be recorded.

Minor (non-blocking): docs/adr/0023-*.md:48 has a stale path link to hypervisor/audit/commitment.py; historical ADR content, fine to leave.

1. AUDIT-COMPLIANCE-1.0.md: restore the blank padding row in the audit
   diagram (the de-claim had duplicated DeltaEngine where CommitmentEngine
   used to be).
2. cspell: drop the global "tion", "reputa" and "Orchestr" entries that would
   mask real typos; instead reword the two ASCII boxes so no word is truncated
   (reputa/tion to author/screen, Orchestr. to the full Orchestrator).
3. isolation.py: delete the dead IsolationLevel.requires_intent_locks property
   (its only consumer, session/intent_locks.py, was removed) and its three
   value assertions in tests/unit/test_session_security.py.
4. BREAKING_CHANGES.md: add an entry recording the 18 removed public
   hypervisor symbols and their agent_runtime re-exports.

Verified: hypervisor suite 640 passed 23 skipped; cspell clean without the
dropped dictionary entries; ruff clean; 0 new broken links.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Liam Crumm <liamcrumm@gmail.com>
@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
🤖 AI Agent: docs-sync-checker — Docs Sync

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Docs Sync

  • README.md -- section on governance-attestation action needs update to reflect its removal.
  • BREAKING_CHANGES.md -- correctly updated with changes to agent-hypervisor and removal of public symbols.
  • action/governance-attestation/README.md -- deleted, which aligns with the removal of the governance-attestation action.

Documentation is in sync.

@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
🤖 AI Agent: test-generator — View details

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Test coverage looks good. No gaps identified.

@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
🤖 AI Agent: security-scanner — Security Review

AI-generated review output. Treat it as untrusted analysis and verify before acting.

Security Review

Severity Finding Fix
High Removal of agent-governance-gate.yml workflow disables governance checks, including policy validation and receipt generation. This could allow policy violations or unverified deployments. Reassess the necessity of removing the agent-governance-gate.yml workflow. If it is no longer needed, ensure equivalent governance checks are implemented elsewhere.
High Removal of governance-attestation and security-scan CI flows eliminates automated governance and security validation. This increases the risk of introducing vulnerabilities or policy violations. Reintroduce these workflows or ensure equivalent checks are implemented in the CI/CD pipeline.
Medium Removal of governance-related symbols from agent-hypervisor may reduce the ability to enforce security and governance policies. Ensure that the removal of these symbols does not compromise the integrity or security of the system. Document alternative mechanisms if applicable.
Medium Deletion of governance-attestation/README.md removes documentation for governance attestation, potentially leading to misuse or misunderstanding of governance requirements. Retain or update the documentation to reflect the current governance processes.

@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
🤖 AI Agent: code-reviewer — Action items:

AI-generated review output. Treat it as untrusted analysis and verify before acting.

TL;DR: 1 blocker, 1 warning. The PR removes critical governance and security-related CI workflows without justification, which could weaken the repository's security posture.

# Sev Issue Where
1 🚨 Removal of critical governance and security-related CI workflows .github/workflows/agent-governance-gate.yml
2 ⚠️ Breaking changes in agent-hypervisor without clear migration timeline BREAKING_CHANGES.md

Action items:

  1. Restore the removed CI workflows or provide a clear justification for their removal and ensure equivalent functionality is implemented elsewhere.

Warnings (fine as follow-up PRs):

# Issue Where
2 Breaking changes in agent-hypervisor without clear migration timeline BREAKING_CHANGES.md

@github-actions

github-actions Bot commented Jul 2, 2026

Copy link
Copy Markdown
🤖 AI Agent: breaking-change-detector — API Compatibility

AI-generated review output. Treat it as untrusted analysis and verify before acting.

API Compatibility

Severity Change Impact
High Removal of public symbols from agent-hypervisor and agent_runtime re-exports: VouchingEngine, VouchRecord, SlashingEngine, LiabilityLedger, LedgerEntryType, LiabilityMatrix, QuarantineManager, QuarantineReason, CausalAttributor, AttributionResult, IntentLockManager, LockIntent, LockContentionError, DeadlockError, FanOutOrchestrator, FanOutPolicy, SagaDSLParser, SagaDefinition, CheckpointManager, SemanticCheckpoint, CommitmentEngine, EphemeralGC, VectorClockManager. These symbols were previously marked as Public Preview stubs and are now removed. Any code relying on these symbols will break.
High Removal of microsoft/agent-governance-toolkit/action/governance-attestation GitHub Action. Any workflows using this action will fail.
High Removal of agent-governance-gate.yml workflow. Any workflows depending on this reusable workflow will fail.

Consequence/obligation + correctness re-review of the current head surfaced
these, all now fixed and verified:

- BREAKING_CHANGES.md: the removed public export set is 23, not 18. Add the 5
  companion types that were also removed from hypervisor and agent_runtime
  __all__: VouchRecord, AttributionResult, LedgerEntryType, LockContentionError,
  DeadlockError.
- constants.py: remove 4 dead VOUCHING_* constants whose only consumer was the
  deleted liability/vouching.py (same orphan class as the already-removed
  enable_blockchain_commitment and requires_intent_locks). Zero consumers remain.
- api-reference.md: fix 3 restored code samples that imported from the wrong
  sub-package and would ImportError on copy-paste (SagaOrchestrator and
  ActionClassifier are top-level; KillReason lives in
  hypervisor.security.kill_switch). Also correct 3 stale event-type values to
  match EventType: ring.breach_detected, security.agent_killed, audit.committed.
- acp-cli.py: benchmark/ to benchmarks/ in a print string left over from the
  directory rename.
- test_spec_audit_compliance_conformance.py: drop "and commitment" from a
  docstring after the commitment sub-tests were removed.

Verified: hypervisor suite 640 passed 23 skipped; agent-os conformance 152
passed; constants.py ruff clean; cspell clean; 0 new broken links; every
hypervisor import across all changed docs resolves (AST sweep of 108).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: Liam Crumm <liamcrumm@gmail.com>
@liamcrumm

Copy link
Copy Markdown
Contributor Author

Deletions verified safe: every removed module, script, tutorial, example, and package stub has zero remaining imports, __all__ entries, nav links, or workspace references on this branch. agt-{core,cli,integrations,protocols} are not on PyPI (all 404). scripts/check_dependency_confusion.py change is comment-only. CI is green.

Four items to close before this is approvable.

  1. docs/specs/AUDIT-COMPLIANCE-1.0.md:131 (introduced by this PR): the ASCII diagram now lists DeltaEngine on both L130 and L131. L131 should be the blank-cell padding row that was there before.
  2. .cspell.json:21: drop "tion" (and "reputa", "Orchestr") from the global word list. These were added to silence truncated words inside ASCII boxes at docs/tutorials/45-shift-left-governance.md:51 and agent-governance-python/agent-os/README.md:440. Adding "tion" to the repo-wide dictionary will mask real typos everywhere. Use <!-- cspell:disable-line --> (or a file-scoped cspell:disable block) at the two sites instead.
  3. agent-governance-python/agent-hypervisor/src/hypervisor/session/isolation.py:34-36: IsolationLevel.requires_intent_locks is now dead. Its only consumer was session/intent_locks.py, which this PR deletes; the remaining references are three value-assertion tests at tests/unit/test_session_security.py:73,80,87. Delete the property and those three assertions in this PR.
  4. BREAKING_CHANGES.md: the only edit is subtractive (drops two actions from an existing entry's affected list). Add a new entry logging the removed public symbols from hypervisor and their agent_runtime re-exports: VouchingEngine, SlashingEngine, LiabilityLedger, LiabilityMatrix, QuarantineManager, QuarantineReason, CausalAttributor, IntentLockManager, LockIntent, FanOutOrchestrator, FanOutPolicy, SagaDSLParser, SagaDefinition, CheckpointManager, SemanticCheckpoint, CommitmentEngine, EphemeralGC, VectorClockManager. Public Preview status permits the removal; it should still be recorded.

Minor (non-blocking): docs/adr/0023-*.md:48 has a stale path link to hypervisor/audit/commitment.py; historical ADR content, fine to leave.

Great feedback, thank you. I have addressed these.

@MohammadHaroonAbuomar MohammadHaroonAbuomar merged commit 54a2c52 into main Jul 2, 2026
141 checks passed
@MohammadHaroonAbuomar MohammadHaroonAbuomar deleted the liamcrumm/hypervisor-remove-stub-features branch July 2, 2026 19:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent-hypervisor agent-hypervisor package dependencies Pull requests that update a dependency file documentation Improvements or additions to documentation scripts/ci/cd size/XL Extra large PR (500+ lines) tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants